home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / coral / install.cha < prev    next >
Text File  |  1994-10-18  |  11KB  |  261 lines
  1. CORAL is an experimental logic-programming language implemented using 
  2. bottom-up techniques. This document describes how to install and run CORAL.
  3. We have successfully installed CORAL on DECStations, HP-700 workstations, 
  4. and SUN 4 and SPARC workstations.
  5.  
  6. The current release of CORAL contains three separate tar files :
  7.  
  8.    coral.x.nobin.tar.Z     :: contains source code, but no binaries
  9.    coral.x.mipsbin.tar.Z   :: contains MIPS binaries
  10.    coral.x.sun4bin.tar.Z   :: contains SUN4 binaries
  11.    coral.x.hpbin.tar.Z       :: contains HP binaries
  12.  
  13. The source code is compatible with g++ and with AT&T CC.
  14. In case you run into problems with CORAL, send mail to coral@cs.wisc.edu.
  15.  
  16. This document contains the following sections :
  17.  
  18.         1) Installing CORAL
  19.         2) Using Binaries
  20.         3) Changing Default Configurations
  21.         4) Using EXODUS for Persistence
  22.         5) Options in Makefiles
  23.         6) Space Requirements
  24.         7) Compiling CORAL
  25.         8) Running Test Scripts
  26.         9) Using EXPLAIN
  27.        10) Other Software Needed
  28.  
  29. If the binaries are to be installed, see sections 1, 2, 8 and 9.
  30. For installing CORAL using the source code, see all sections except 2.
  31.  
  32. Installing CORAL
  33. ----------------
  34.  
  35. The first thing to do is to get access to the CORAL system code. If
  36. you are reading this, it is most probable that you already do have
  37. the code too. However, just in case you bought this installation document
  38. in its bestselling paperback edition from your local bookstore :-),
  39. you should know that CORAL is available by anonymous ftp from
  40. ftp.cs.wisc.edu.
  41.  
  42. The file that you ftp over is a 'tar' file called coral.x.yyy.tar.Z.
  43. To set up CORAL on your machine, you need to store the tar file in an 
  44. appropriate directory, and then do the following :
  45.  
  46.      ``zcat coral.xx.tar.Z | tar xvf -''.
  47.  
  48.      (Alternatively, ``uncompress coral.xx.tar'', followed by 
  49.      ``tar xvf coral.xx.tar''.)
  50.  
  51. Now a whole directory system should have been created with the root
  52. of the system called `coral'. If your tar file contained the CORAL src
  53. code, all the directories listed below will have been created :
  54.  
  55.     coral
  56.     coral/bin
  57.     coral/doc
  58.     coral/explain
  59.     coral/EXAMPLES
  60.     coral/help
  61.     coral/includes
  62.     coral/interface
  63.     coral/magic
  64.     coral/src
  65.  
  66.  
  67. The directory `coral' is the root of the CORAL system, and there
  68. should be an environment variable called CORALROOT which has the value
  69. of this root directory. For example, CORALROOT=/usr/coral
  70. At this stage, you should add this to your environment using `setenv',
  71. and also make the change to your .cshrc file so that it gets done
  72. automatically in the future. Also, (CORALROOT)/bin should be added
  73. to your PATH variable. This is very important, since all the CORAL
  74. executables reside in the CORAL/bin directory or have links in it.
  75. Also, the test scripts to be run use csh, and so will read the .cshrc
  76. file.
  77.  
  78. There are a couple of startup files in the (CORALROOT) directory that
  79. are important. One is .coralrc, which is read and processed initially
  80. by the CORAL interpreter. We recommend that you put in your favorite
  81. CORAL alias definitions in the .coralrc file. The other file is
  82. .sm_config which is used to configure the EXODUS storage manager.
  83. Both these files should be moved to your HOME directory.
  84.  
  85. Using Binaries
  86. -----------------------------
  87.  
  88. If you do not wish to recompile CORAL, and would simply like to use the
  89. binaries in the release, here's what you need to do :
  90.  
  91.    cd to the (CORALROOT)
  92.    edit the file 'makefile' and ensure that CORALBIN is set
  93.      to CORALROOT/bin/SUN4, CORALROOT/bin/MIPS or  CORALROOT/bin/HP,
  94.      depending on the type of machine you are working on.
  95.    type `make'.
  96.  
  97. This installs the binaries, and CORAL is ready to use. After this
  98. you can ignore the rest of the installation document, and look only
  99. at the section on running test scripts.
  100.  
  101.  
  102. Changing default configurations
  103. -------------------------------
  104.  
  105. The default configuration of the CORAL system is controlled by a set
  106. of default definitions in the file (CORALROOT)/includes/config.h. It is
  107. remotely possible that you might want to change certain parameters
  108. before compiling. However, we recommend that before you attempt to
  109. do so, you understand the use of the defaults in the code, and the
  110. effects of modifying them. It should not be necessary to modify any
  111. of these values unless you intend to extend the system to some
  112. significant degree. In any case, most of these defaults can be changed
  113. from the CORAL prompt, and commands to change them can be included in
  114. the startup .coralrc file. Once you have CORAL up and running, you can
  115. type 'help(defaults).' to get information on how to change the default
  116. values.
  117.  
  118. Using EXODUS for persistence
  119. ----------------------------
  120.  
  121. At this stage, you should be aware that CORAL can be used with or
  122. without persistent relations. The conditional compilation can be
  123. controlled by setting some flags in the makefiles (see next subsection).
  124. The persistence is built on top of the EXODUS storage manager, which
  125. is a separate piece of software, also available from UW-Madison
  126. at ftp.cs.wisc.edu. However it is your responsibility to obtain
  127. and install the EXODUS storage manager Version 3.*. The following
  128. five files are needed:
  129.  
  130.     sm_client.h
  131.     lib_smclient.a
  132.     formatvol
  133.     sm_server
  134.     diskrw
  135.  
  136. Look at the options in (CORALROOT)/make_include. Two variables deal with 
  137. EXODUS. EXODUS_LIB_DIR is used to specify the directory in which lib_smclient.a
  138. resides, and EXODUS_INCLUDE_DIR is used to specify where sm_client.h resides.
  139.  
  140. We have provided a .sm_config file that provides a sample EXODUS config file
  141. for Coral. You will need to modify it as required (refer to the EXODUS
  142. Installation Manual for details). For starters, make sure that the machine
  143. names, port ids and file names used in the file are valid. The default
  144. .sm_config file uses a data "disk", a log "disk" and a temporary "disk".
  145. The very first time around, you will need to use formatvol to initialize 
  146. these "disks". For the default .sm_config, this involves executing
  147. "formatvol -volume 9000; formatvol -volume 8000; formatvol -volume 7000".
  148. After that, you need to open a separate window and run sm_server, which is 
  149. the EXODUS Storage Manager. If the Storage Manager is up and running, the 
  150. CORAL interpreter will automatically connect to it, provided it has been 
  151. compiled to support persistent relations, and provided it is invoked with 
  152. the -e flag (type "coral -help" to see the various command line flags
  153. that CORAL supports). Within CORAL, type "help(persistence)." to get
  154. information on how to use persistent relations.
  155.  
  156. The binary versions of CORAL are compiled _without_ 
  157. the persistence option !! If you need to use persistence, you will have to 
  158. obtain the CORAL sources and compile.  
  159.  
  160. Options in Makefiles
  161. --------------------
  162.  
  163. In order to specify options to any makefiles, you only need to
  164. modify (CORALROOT)/make_include. This file is included in all
  165. the other makefiles.
  166.  
  167. The (CORALROOT)/make_include file contains comments explaining
  168. the use of every flag and makefile variable. One important point
  169. to note is that CORAL can be compiled with or without persistence.
  170. You should also indicate where you have installed the Flex scanner
  171. by setting the make variable SCANNER.
  172.  
  173. Space Requirements
  174. ------------------
  175.  
  176. The sizes of the three versions of the tar files when uncompressed
  177. and untarred is :
  178.  
  179.   sources only   :  ~15.5 M
  180.   MIPS binaries  :  ~12 M
  181.   SUN4 binaries  :  ~10 M
  182.   HP binaries     :  ??
  183.  
  184. The following paragraph applies only for the version with the source 
  185. files. When you start compilation using the source files, the entire
  186. system can grow to around 40 M, if compiled without the -g
  187. flag (as is the default), and can grow to 70M if compiled with
  188. the -g flag. However, much of this space is occupied by .o
  189. files than can be deleted if space is a problem. Also, the
  190. executables can be stripped to reduce space utilization.
  191. The size of the coral executable is around 1.15M when compiled
  192. with the debug flag. If the coral executable is stripped,
  193. incremental loading is not possible (refer to the user manual
  194. on this one). All these figures refer to compilation on the
  195. DECstation 5000. The figures on a SUN4 machine are slightly lower.
  196. Note that these figures do not take into account the space
  197. required for the Explain tool, which is based on Interviews, and
  198. could take upto 5M without the -g flag. 
  199.  
  200. Compiling CORAL
  201. ---------------
  202.  
  203. Once you have got to this point, all that remains is to install the
  204. system. To do this, cd to the (CORALROOT), and type `make install'.
  205. This will start a compilation of the entire CORAL system (which
  206. will take quite a while : approx. 40 minutes on a DECStation 5000).
  207. When it completes, you have CORAL compiled and ready.
  208.  
  209. Running test scripts
  210. --------------------
  211.  
  212. At this stage, we recommend you run the test suites that sit in
  213. the (CORALROOT)/REGRESSION directory. These are run by typing the commands:
  214.  
  215.     cd (CORALROOT)/REGRESSION
  216.     (cd accept1.tst; test_suite)
  217.     (cd accept2.tst; test_suite)
  218.  
  219. This might generate some warning
  220. messages, but there should be no error messages. The entire `test_suite'
  221. should run in a few minutes.
  222.  
  223. If you run into any problems in reaching this point, send mail to
  224. coral@cs.wisc.edu, and we'll try to fix it asap. Otherwise, the CORAL
  225. manual and overview documents
  226. should carry you on from here.
  227.  
  228. Using EXPLAIN
  229. -------------
  230.  
  231. This release of CORAL is accompanied by an 'Explanation Tool'
  232. that resides in the (CORALROOT)/explain directory. This
  233. tool allows one to graphically visualize the execution of a
  234. CORAL program. It is based on InterViews which is available by
  235. anonymous ftp from interviews.stanford.edu. There are
  236. independent installation instructions for it in the file
  237. (CORALROOT)/explain/Installation. There is also a README file
  238. in (CORALROOT)/explain/ that contains further information on
  239. the Explain tool.
  240.  
  241.  
  242. Other Software Needed
  243. ---------------------
  244.  
  245. If you require the use of persistent data, you will need to get the 
  246. Exodus Storage Manager v3.*, which is freely available from ftp.cs.wisc.edu.
  247.  
  248. 1) g++ and Flex v2.4.6 are available by anonymous ftp from prep.ai.mit.edu
  249.  
  250. 2) you will also need nawk, which is a variant of awk to process testscripts
  251. and table data. If you do not have nawk, make a link to awk in your coral/bin
  252. directory and call it nawk.
  253.  
  254. 3) Most of the CORAL scripts use /bin/csh.
  255.  
  256. We hope you enjoy using CORAL; your feedback would be appreciated.
  257. If you extend CORAL, and want to make your changes available to the
  258. world, do get in touch with Raghu Ramakrishnan.
  259.  
  260.  
  261.